---
title: Turso & Astro
description: Build locally with a SQLite file and deploy globally using Turso.
sidebar:
  label: Turso
type: backend
logo: turso
stub: false
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

[Turso](https://turso.tech) is a distributed database built on libSQL, a fork of SQLite. It is optimized for low query latency, making it suitable for global applications.

## Initializing Turso in Astro

### Prerequisites

- The [Turso CLI](https://docs.turso.tech/cli/introduction) installed and signed in
- A [Turso](https://turso.tech) Database with schema
- Your Database URL
- An Access Token

### Configure environment variables

Obtain your database URL using the following command:

```bash
turso db show <database-name> --url
```

Create an auth token for the database:

```bash
turso db tokens create <database-name>
```

Add the output from both commands above into your `.env` file at the root of your project. If this file does not exist, create one.

```ini title=".env"
TURSO_DATABASE_URL=libsql://...
TURSO_AUTH_TOKEN=
```

:::caution
Do not use the `PUBLIC_` prefix when creating these private [environment variables](/en/guides/environment-variables/). This will expose these values on the client.
:::

### Install LibSQL Client

Install the `@libsql/client` to connect Turso to Astro:

<PackageManagerTabs>
  <Fragment slot="npm">
    ```shell
    npm install @libsql/client
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```shell
    pnpm add @libsql/client
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```shell
    yarn add @libsql/client
    ```
  </Fragment>
</PackageManagerTabs>

### Initialize a new client

Create a file `turso.ts` in the `src` folder and invoke `createClient`, passing it `TURSO_DATABASE_URL` and `TURSO_AUTH_TOKEN`:

```ts title="src/turso.ts"
import { createClient } from "@libsql/client/web";

export const turso = createClient({
  url: import.meta.env.TURSO_DATABASE_URL,
  authToken: import.meta.env.TURSO_AUTH_TOKEN,
});
```

## Querying your database

To access information from your database, import `turso` and [execute a SQL query](https://docs.turso.tech/sdk/ts/reference#simple-query) inside any `.astro` component.

The following example fetches all `posts` from your table, then displays a list of titles in a `<BlogIndex />` component:

```astro title="src/components/BlogIndex.astro"
---
import { turso } from '../turso'

const { rows } = await turso.execute('SELECT * FROM posts')
---

<ul>
  {rows.map((post) => (
    <li>{post.title}</li>
  ))}
</ul>
```

### SQL Placeholders

The `execute()` method can take [an object to pass variables to the SQL statement](https://docs.turso.tech/sdk/ts/reference#placeholders), such as `slug`, or pagination.

The following example fetches a single entry from the `posts` table `WHERE` the `slug` is the retrieved value from `Astro.params`, then displays the title of the post.

```astro title="src/pages/index.astro"
---
import { turso } from '../turso'

const { slug } = Astro.params

const { rows } = await turso.execute({
  sql: 'SELECT * FROM posts WHERE slug = ?',
  args: [slug!]
})
---

<h1>{rows[0].title}</h1>
```

## Turso Resources
- [Turso Docs](https://docs.turso.tech)
- [Turso on GitHub](https://github.com/tursodatabase)
- [Using Turso to serve a Server-side Rendered Astro blog's content](https://blog.turso.tech/using-turso-to-serve-a-server-side-rendered-astro-blogs-content-58caa6188bd5)
